Duckietown is a robotics educations and outreach effort.

The most tangible goal of the project is to provide a low-cost educational platform for learning autonomy, consisting of the Duckiebots, an autonomous robot, and the Duckietowns, the infrastructure in which the Duckiebots navigates.

However, we focus on the learning experience as a whole, by providing a set of modules teaching plans and other guides, as well as a curated role-play experience.

We have two targets:

1. For instructors, we want to create a “class-in-a-box” that allows to offer a modern and engaging learning experience. Currently, this is feasible at the advanced undergraduate and graduate level, though in the future we would like to present the platform as multi-grade experiences.
2. For self-guided learners, we want to create a “self-learning experience”, that allows to go from zero knowledge of robotics to graduate-level understanding.

In addition, the Duckietown platform has been used as a research platform.

While we are at the early phases of the project, many people have been used the materials in the past year.

The best way to get a sense of how the platform looks is to watch these videos. They show off the capabilities of the platform.

This video is part of the Red Hat documentary:

These papers present a more formal description of the technical side of the projecrt as well as the educational side.

This paper [1] describes the course design for Duckietown: learning objectives, teaching methods, etc.

This video is a Duckumentary about the first version of the class, during Spring 2016. The Duckumentary was shot by Chris Welch.

The paper [2] describes the Duckiebot and its software. With 29 authors, we made the record for a robotics conference.

Duckietown started as an MIT class during Spring 2016.

In 2017, the class will be offered contemporaneously at:

• ETH Zurich
• University of Montreal
• University of Chicago

as well as:

If you are an instructor, please jump to Section 3.2.

If you are a self-guided learner, please jump to Section 3.3.

If you are a company, and interested in working with Duckietown, please jump to Section 3.4.

Duckietown is a low-cost educational and research platform.

Yes. All materials are released according to an open source license.

Not quite! Please sign up to our mailing list to get notified when things are a bit more ready.

See the next section, Getting started.

If you would like to help actively, please email duckietown@mit.edu.

Please get in touch with us at duckietown@mit.edu. We will be happy to get you started and sign you up to the Duckietown instructors mailing list.

Compared to other educational robotics projects, the presence of the duckies is what makes this project stand out. Why the duckies?

We want to present robotics in an accessible and friendly way.

Currently, Duckietown has the following accounts:

• Github: for source code, and issue tracking;
• Slack: a forum for wide communication;
• Twist: to be used for instructors coordination;
• Google Drive: to be used for instructors coordination, maintaining TODOs, etc;
• Dropbox Folders (part of Andrea’s personal accounts): to be abandoned;
• Vimeo, for storing the videos;
• The duckietown-teaching mailing list, for low-rate communication with instructors;
• We also have a list of addresses, of people signed up on the website, that we didn’t use yet;
• The Facebook page.

If you are an international contributor:

• Sign up on Slack, to keep up with the project.
• (optional) Get Github permissions if you do frequent updates to the repositories.

All the documentation is in the repository duckietown/duckuments.

The documentation is written as a series of small files in Markdown format.

It is then processed by a series of scripts to create this output:

• a publication-quality PDF;
• an online HTML version, split in multiple pages and with comments boxes.

The simplest way to contribute to the documentation is to click any of the “✎” icons next to the headers.

They link to the “edit” page in Github. There, one can make and commit the edits in only a few seconds.

In the multiple-page version, each page also includes a comment box powered by a service called Disqus. This provides a way for people to write comments with a very low barrier. (We would periodically remove the comments.)

In the following, we are going to assume that the documentation system is installed in ~/duckuments. However, it can be installed anywhere.

We are also going to assume that you have setup a Github account with working public keys.

$ which python
/home/![user]/duckuments/deploy/bin/python

Then:

$ cd ~/duckuments
$ make duckuments-dist

This creates the directory duckuments-dist, which contains another checked out copy of the repository, but with the branch gh-pages, which is the branch that is published by Github using the “Github Pages” mechanism.

~/duckuments/.git
~/duckuments/duckuments-dist/.git

To compile the docs, run make clean compile:

$ make clean compile

To see the result, open the file

./duckuments-dist/master/duckiebook/index.html

This is the workflow:

1. Edit the Markdown in the master branch of the duckuments repository.
2. Run make compile to make sure it compiles.
3. Commit the Markdown and push on the master branch.

Done. A bot will redo the compilation and push the changes in the gh-pages branch.

Step 2 is there so you know that the bot will not encounter errors.

To deploy the documentation, jump into the DUCKUMENTS/duckuments-dist directory.

Run the command git branch. If the out does not say that you are on the branch gh-pages, then one of the steps before was done incorrectly.

$ cd $DUCKUMENTS/duckuments-dist
$ git branch
...
* gh-pages
...

Now, after triple checking that you are in the gh-pages branch, you can use git status to see the files that were added or modified, and simply use git add, git commit and git push to push the files to Github.

You can use $\LaTeX$ math, environment, and references. For example, take a look at

$$ x^2 = \int_0^t f(\tau)\ \text{d}\tau $$

or refer to Proposition 1.

The above was written as in Figure 1.

You can use $\LaTeX$ math, environment, and references.
For example, take a look at

\[
    x^2 = \int_0^t f(\tau)\ \text{d}\tau
\]

or refer to [](#prop:example).

\begin{proposition}[Proposition example]\label{prop:example}
This is an example proposition: $2x = x + x$.
\end{proposition}

Use the syntax “![name]” for describing the variables in the code.

$ ssh ![robot name].local

For example, to obtain:

    $ ssh ![robot name].local

Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the LaTeX interpreter.

Use the string $ to write the dollar symbol $, otherwise it gets confused with LaTeX math materials. Also notice that you should probably use “USD” to refer to U.S. dollars.

Other symbols to escape are shown in Table 1.

Use the kbd element for keystrokes.

Press <kbd>a</kbd> then <kbd>Ctrl</kbd>-<kbd>C</kbd>.

For any element, adding an attribute called figure-id with value fig:![figure ID] or tab:![table ID] will create a figure that wraps the element.

For example:

<div figure-id="fig:![figure ID]">
    ![figure content]
</div>

It will create HMTL of the form:

<div id='fig:code-wrap' class='generated-figure-wrap'>
    <figure id='fig:![figure ID]' class='generated-figure'>
        <div>
            ![figure content]
        </div>
    </figure>
</div>

To add a caption, add an attribute figure-caption:

<div figure-id="fig:![figure ID]" figure-caption="This is my caption">
    ![figure content]
</div>

Alternatively, you can put anywhere an element figcaption with ID ![figure id]:caption:

<element figure-id="fig:![figure ID]">
    ![figure content]
</element>

<figcaption id='fig:![figure ID]:caption'>
    This the caption figure.
</figcaption>

To refer to the figure, use an empty link:

Please see [](#fig:![figure ID]).

The code will put a reference to “Figure XX”.

The shortcuts col2, col3, col4, col5 are expanded in tables with 2, 3, 4 or 5 columns.

The following code:

<col2 figure-id="tab:mytable" figure-caption="My table">
    <span>A</span>
    <span>B</span>
    <span>C</span>
    <span>D</span>
</col2>

gives the following result:

The following holds for all technical writing.

• The documentation is written in correct English.

• Do not say “should” when you mean “must”. “Must” and “should” have precise meanings and they are not interchangeable. These meanings are explained in this document.

• “Please” is unnecessary in technical documentation.

“Please remove the SD card.”

“Remove the SD card”.

• Do not use colloquialisms or abbreviations.

“The pwd is ubuntu.”

“The password is ubuntu.”

• Do not use emojis.

• Do not use ALL CAPS.

• Make infrequent use of bold statements.

• Do not use exclamation points.

• It’s ok to use “it’s” instead of “it is”, “can’t” instead of “cannot”, etc.

• All the filenames and commands must be enclosed in code blocks using Markdown backticks.

“Edit the ~/.ssh/config file using vi.”

“Edit the ~/.ssh/config file using vi.”

• Ctrl-C, ssh etc. are not verbs.

“Ctrl-C from the command line”.

“Use Ctrl-C from the command line”.

• Subtle humor and puns about duckies are encouraged.

Use either “laptop” or “duckiebot” (not capitalized, as a hostname) as the prefix for the command line.

For example, for a command that is supposed to run on the laptop, use:

laptop $ cd ~/duckietown

It will become:

laptop $ cd ~/duckietown

For a command that must run on the Duckiebot, use:

duckiebot $ cd ~/duckietown

It will become:

duckiebot $ cd ~/duckietown

If the command is supposed to be run on both, omit the hostname:

$ cd ~/duckietown

• “Duckiebot” is always capitalized.

• Use “Raspberry Pi”, not “PI”, “raspi”, etc.

• These are other words frequently misspelled:

  5 GHz WiFi

When the user must edit a file, just say: “edit /this/file”.

Writing down the command line for editing, like the following:

$ vi /this/file

is too much detail.

(If people need to be told how to edit a file, Duckietown is too advanced for them.)

Write the documentation as if every step succeeds.

Then, at the end, make a “Troubleshooting” section.

Organize the troubleshooting section as a list of symptom/resolution.

The following is an example of a troubleshooting section.

Each atom has the following properties:

• An ID (alphanumeric + - and ‘_’). The ID is used for cross-referencing. It is the same in all languages.
• A type, as above.

There might be different versions of each atom. This is used primarily for dealing with translations of texts, different representations of the same image, Powerpoint vs Keynote, etc.

A version is a tuple of attributes.

The attributes are:

• Language: A language code, such as en-US (default), zh-CN, etc.

• Mime type: a MIME type.

Each atom version has:

• A status: one of draft, ready.
• A human-readable title.
• A human-readable summary (1 short paragraph).

For the text-like resources, they are described in Markdown files.

The name of the file does not matter.

All files are encoded in UTF-8.

Each file starts with a H1 header. The contents is the title.

The header has the following attributes:

1. The ID. ({#ID})
2. The language is given by an attribute lang ({lang=en-US}).
3. The type is given by an attribute type ({type=demo}).
4. The status is given by an attribute status ({status=draft}).

Here is an example of a header with all the attributes:

# Odometry calibration {#odometry-calibration  lang=en-US type='text/theory' status=ready}

This first paragraph will be used as the "summary" for this text.

And this is how the Italian translation would look like:

# Calibrazione dell'odometria {#odometry-calibration  lang=it type='text/theory' status=draft}

Questo paragrafo sarà usato come un sommario del testo.

In the text, you describe the semantic graph using tags and IDs.

In Markdown, you can give IDs to sections using the syntax:

# Setup step 1  {#setup-step1}

This is the first setup step.

Then, when you write the second step, you can add a a semantic edge using the following.

# Setup step 2  {#setup-step2}

This is the second setup step.

Requires: You have completed the first step in [](#setup-step1).

The following table describes the syntax for the different types of semantic links:

Requires: You need to have done [](#setup-step).

Recommended: It is better if you have setup Wifi as in [](#setup-wifi).

Reference: For more information about rostopic,
    see [](#rostopic).

See also: If you are interested in feature detection, you might
    want to learn about [SIFT](#SIFT).

Configuration D17-0: Only camera and motors.

Configuration D17-0+w: Previous one + an additional WiFi card (Edimax).

Configuration D17-0+j: Previous one + joystick.

Configuration D17-1: LED lights and bumpers

Download the image from the page

https://ubuntu-mate.org/download/

The file we are looking for is:

filename: ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
    size: 1.2 GB
  SHA256: dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2

After download, run the command sha256sum to make sure you have the right version:

laptop $ sha256sum ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2

If the string does not correspond exactly, your download was corrupted. Delete the file and try again.

Then decompress using the command xz:

laptop $ xz -d ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz

Next, burn the image on to the SD card.

The Raspberry Pi is not accessible by SSH by default.

Run raspi-config:

duckiebot $ sudo raspi-config

choose “3. Interfacing Options”, and enable SSH,

We need to enable the camera and the I2C bus.

choose “3. Interfacing Options”, and enable camera, and I2C.

Also disable the graphical boot

Install these packages.

Etckeeper:

duckiebot $ sudo apt install etckeeper

Editors / shells:

duckiebot $ sudo apt install -y vim emacs byobu zsh

Git:

duckiebot $ sudo apt install -y git git-extras

Other:

duckiebot $ sudo apt install htop atop nethogs iftop
duckiebot $ sudo apt install aptitude apt-file

Development:

duckiebot $ sudo apt install -y build-essential libblas-dev liblapack-dev libatlas-base-dev gfortran libyaml-cpp-dev

Python:

duckiebot $ sudo apt install -y python-dev ipython python-sklearn python-smbus
duckiebot $ sudo pip install scipy --upgrade

I2C:

duckiebot $ sudo apt install -y i2c-tools

First, mark the kernel packages as not upgradeable:

$ sudo apt-mark hold raspberrypi-kernel raspberrypi-kernel-headers
raspberrypi-kernel set on hold.
raspberrypi-kernel-headers set on hold

Then, download and install the Edimax driver from this repository.

Install ROS.

This is the old version.

There are two files that are important to edit.

The file /etc/network/interfaces should look like this:

# interfaces(5) file used by ifup(8) and ifdown(8)
# Include files from /etc/network/interfaces.d:
#source-directory /etc/network/interfaces.d

auto wlan0

# The loopback network interface
auto lo
iface lo inet loopback

# Wireless network interface
allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

The file /etc/wpa_supplicant/wpa_supplicant.conf should look like this:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
ssid="duckietown"
psk="quackquack"
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
auth_alg=OPEN
}
network={
   key_mgmt=NONE
}

The files that describe the network configuration are in the directory

/etc/NetworkManager/system-connections/

This is the contents of the connection file duckietown, which describes how to connect to the duckietown wireless network:

[connection]
id=duckietown
uuid=e9cef1bd-f6fb-4c5b-93cf-cca837ec35f2
type=wifi
permissions=
secondaries=
timestamp=1502254646

[wifi]
mac-address-blacklist=
mac-address-randomization=0
mode=infrastructure
ssid=duckietown

[wifi-security]
group=
key-mgmt=wpa-psk
pairwise=
proto=
psk=quackquack

[ipv4]
dns-search=
method=auto

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=auto

This is the file

/etc/NetworkManager/system-connections/create-5ghz-network

Contents:

[connection]
id=create-5ghz-network
uuid=7331d1e7-2cdf-4047-b426-c170ecc16f51
type=wifi
# Put the Edimax interface name here:
interface-name=![wlx74da38c9caa0 - to change]
permissions=
secondaries=
timestamp=1502023843

[wifi]
band=a
# Put the Edimax MAC address here
mac-address=![74:DA:38:C9:CA:A0 - to change]
mac-address-blacklist=
mac-address-randomization=0
mode=ap
seen-bssids=
ssid=duckiebot-not-configured

[ipv4]
dns-search=
method=shared

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=ignore

Note that there is an interface name and MAC address that need to be changed on each PI.

This enables the SSH server:

$ sudo systemctl enable ssh

Do the following:

Create an empty file using the dd (device-to-device copy) command:

duckiebot $ sudo dd if=/dev/zero of=/swap0 bs=1M count=512

This is for a 512 MB swap space.

Format the file for use as swap:

duckiebot $ sudo mkswap /swap0

Add the swap file to the system configuration:

duckiebot $ sudo vi /etc/fstab

Add this line to the bottom:

/swap0 swap swap

Activate the swap space:

duckiebot $ sudo swapon -a

First, make vi the default editor, using

$ sudo update-alternatives --config editor

and then choose vim.basic.

Then run:

$ sudo visudo

And then change this line:

%sudo   ALL=(ALL:ALL) ALL

into this line:

%sudo   ALL=(ALL:ALL) NOPASSWD:ALL

Install Ubuntu 16.04.2.

On the choice of username: During the installation, create a user for yourself with a username different from ubuntu, which is the default. Otherwise, you may get confused later.

Use etckeeper to keep track of the configuration in /etc:

laptop $ sudo apt install etckeeper

Install ssh to login remotely and the server:

laptop $ sudo apt install ssh

Use byobu:

laptop $ sudo apt install byobu

Use vim:

laptop $ sudo apt install vim

Use htop to monitor CPU usage:

laptop $ sudo apt install htop

Additional utilities for git:

laptop $ sudo apt install git git-extras

Other utilities:

laptop $ sudo apt install avahi-utils ecryptfs-utils

Install ROS on your laptop.

Set up passwordless sudo.

On the laptop, download the compressed image at this URL:

https://www.dropbox.com/s/1p4am7erdd9e53r/duckiebot-RPI3-AC-aug10.img.xz?dl=1

The size is 2.5 GB.

You can use:

$ curl -o duckiebot-RPI3-AC-aug10.img.xz ![URL above]

Uncompress the file:

$ xz -d -k duckiebot-RPI3-AC-aug10.img.xz

This will create a file of 32 GB in size.

To make sure that the image is downloaded correctly, compute its hash using the program sha256sum:

$ sha256sum duckiebot-RPI3-AC-aug10.img
2ea79b0fc6353361063c89977417fc5e8fde70611e8afa5cbf2d3a166d57e8cf  duckiebot-ac-aug10.img

Compare the hash that you obtain with the hash above. If they are different, there was some problem in downloading the image.

Next, burn the image on disk.

Put the SD Card in the Duckiebot.

Turn on the Duckiebot by connecting the power cable to the battery.

You can login to the Duckiebot in two ways:

1. Through an Ethernet cable.
2. Through a duckietown WiFi network.

In the worst case, you can use an HDMI monitor and a USB keyboard.

To test that the Duckiebot is connected, try to ping it.

The hostname of a freshly-installed duckiebot is duckiebot-not-configured:

laptop $ ping duckiebot-not-configured.local

You should see output similar to the following:

PING duckiebot-not-configured.local (![X.X.X.X]): 56 data bytes
64 bytes from ![X.X.X.X]: icmp_seq=0 ttl=64 time=2.164 ms
64 bytes from ![X.X.X.X]: icmp_seq=1 ttl=64 time=2.303 ms
![...]

Next, try to log in using SSH, with account ubuntu:

laptop $ ssh ubuntu@duckiebot-not-configured.local

The password is ubuntu.

By default, the robot boots into Byobu.

Please see Section 81.1 for an introduction to Byobu.

Not sure it’s a good idea to boot into Byobu.

D17-0+w The Duckiebot in configuration D17-C0+w can create a WiFi network.

It is a 5 GHz network; this means that you need to have a 5 GHz WiFi adapter in your laptop.

First, make sure that the Edimax is correctly installed. Using iwconfig, you should see four interfaces:

duckiebot $ iwconfig
wlx![AABBCCDDEEFFGG]  unassociated  Nickname:"rtl8822bu"

![...]

lo        no wireless extensions.

enxb827eb1f81a4  no wireless extensions.

wlan1     IEEE 802.11bgn  ESSID:"duckietown"

![...]

Make note of the name wlx![AABBCCDDEEFFGG].

Look up the MAC address using the command:

duckiebot $ ifconfig wlx![AABBCCDDEEFFGG]
wlx74da38c9caa0 Link encap:Ethernet  HWaddr ![AA:BB:CC:DD:EE:FF:GG]

Then, edit the connection file

/etc/NetworkManager/system-connections/create-5ghz-network

Make the following changes:

• Where it says interface-name=![...], put “wlx![AABBCCDDEEFFGG]”.
• Where it says mac-address=![...], put “![AA:BB:CC:DD:EE:FF:GG]”.
• Where it says ssid=duckiebot-not-configured, put “ssid=![robot name]”.

Reboot.

At this point you should see a new network being created named “![robot name]”.

You can connect with the laptop to that network.

If the Raspberry Pi’s network interface is connected to the duckietown network and to the internet, the Raspberry Pi will act as a bridge to the internet.

This part should not be necessary anymore

The Duckiebot is configured by default to connect to a wireless network with SSID duckietown. If that is not your SSID then you will need to change the configuration.

You can add a new network by editing the file:

/etc/wpa_supplicant/wpa_supplicant.conf

You will see a block like the following:

network={
 ssid="duckietown"
 scan_ssid=1
 psk="quackquack"
 priority=10
}

Add a new one with your SSID and password.

This assumes you have a roughly similar wireless network setup - if not then you might need to change some of the other attributes.

Next, we need to update to bring the system up to date.

Use these commands

duckiebot $ sudo apt update
duckiebot $ sudo apt dist-upgrade

It is now time to give a name to the Duckiebot.

These are the criteria:

• It should be a simple alphabetic string (no numbers or other characters like “-”, “_”, etc.) .
• It will always appear lowercase.
• It cannot be a generic name like “duckiebot”, “robot” or similar.

From here on, we will refer to this string as “![robot name]”. Every time you see ![robot name], you should substitute the name that you chose.

We will put the robot name in configuration files.

duckiebot $ sudo vi ![filename]

Edit the file

/etc/hostname

and put “![robot name]” instead of duckiebot-not-configured.

Also edit the file

/etc/hosts

and put “![robot name]” where duckiebot-not-configured appears.

The first two lines of /etc/hosts should be:

127.0.0.1   localhost
127.0.1.1   ![robot name]

Then reboot the Raspberry Pi using the command

$ sudo reboot

After reboot, log in again, and run the command hostname to check that the change has persisted:

$ hostname
![robot name]

You must not use the ubuntu user for development. Instead, you need to create a new user.

Choose a user name, which we will refer to as ![username].

To create a new user:

duckiebot $ sudo useradd -m ![username]

Make the user an administrator by adding it to the group sudo:

duckiebot $ sudo adduser ![username] sudo

Make the user a member of the group input and i2c

duckiebot $ sudo adduser ![username] input
duckiebot $ sudo adduser ![username] video
duckiebot $ sudo adduser ![username] i2c

Set the shell bash:

duckiebot $ sudo chsh -s /bin/bash andrea

To set a password, use:

duckiebot $ sudo passwd ![username]

At this point, you should be able to login to the new user from the laptop using the password:

laptop $ ssh ![username]@![robot name]

Next, you should repeat some steps that we already described.

If you know what you are doing, you are welcome to install and use additional shells, but please keep Bash as be the default shell. This is important for ROS installation.

For the record, our favorite shell is ZSH with oh-my-zsh.

Check that the camera is connected using this command:

duckiebot $ vcgencmd get_camera
supported=1 detected=1

If you see detected=0, it means that the hardware connection is not working.

You can test the camera right away using a command-line utility called raspistill.

Use the raspistill command to capture the file out.jpg:

duckiebot $ raspistill -t 1 -o out.jpg

Then download out.jpg to your computer using scp for inspection.

Clone the repository in the directory ~/duckietown:

duckiebot $ git clone git@github.com:duckietown/Software.git ~/duckietown

For the above to succeed you should have a Github account already set up.

It should not ask for a password.

All the following commands should be run in the ~/duckietown directory:

duckiebot $ cd ~/duckietown

Now we are ready to make the workspace. First you need to source the baseline ROS environment:

duckiebot $ source /opt/ros/kinetic/setup.bash

Then, build the workspace using:

duckiebot $ catkin_make -C catkin_ws/

AC: I had to run it twice. The first time it complained:

In file included from /home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/src/apriltag_detector.cpp:1:0:
/home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/include/apriltags_ros/apriltag_detector.h:6:41: fatal error: duckietown_msgs/BoolStamped.h: No such file or directory

On the robot edit the file

~/duckietown/catkin_ws/src/duckietown/machines

You will see something like this:

<launch>
    <arg name="env_script_path" default="~/duckietown/environment.sh"/>

    <machine name="![robot name]" address="![robot name].local" user="![username]"
             env-loader="$(arg env_script_path)"/>
        ...
    ...
</launch>

Now, duplicate a <machine> line between <launch> and </launch>, and replace the name and address string with the name of your vehicle.

For example, for Andrea, ![robot name] = emma and ![username] = andrea. So, he would add this line:

<machine name="emma" address="emma.local" user="andrea" env-loader="$(arg env_script_path)"/>

Commit and push the new machines file. ( No, don’t commit the machines file.)

Plug the joystick receiver in one of the USB port on the Raspberry Pi.

To make sure that the joystick is detected, run:

duckiebot $ ls /dev/input/

and check if there is a device called js0 on the list.

duckiebot $ groups
![username] sudo input i2c

To test whether or not the joystick itself is working properly, run:

duckiebot $ jstest /dev/input/js0

Move the joysticks and push the buttons. You should see the data displayed change according to your actions.

SSH into the Raspberry Pi and run the following from the duckietown directory:

duckiebot $ cd ~/duckietown
duckiebot $ source environment.sh

The environment.sh setups the ROS environment at the terminal (so you can use commands like rosrun and roslaunch).

Now make sure the motor shield is connected.

Run the command:

duckiebot $ roslaunch duckietown joystick.launch veh:=![robot name]

If there is no “red” output in the command line then pushing the left joystick knob controls throttle - right controls steering.

This is the expected result of the commands:

It is possible you will have to unplug and replug the joystick or just push lots of buttons on your joystick until it wakes up. Also make sure that the mode switch on the top of your joystick is set to “X”, not “D”.

Is all of the above valid with the new joystick?

Close the program using Ctrl-C.

Generally speaking, you can terminate any roslaunch command with Ctrl-C.

To completely shutdown the robot, issue the following command:

duckiebot $ sudo shutdown -h now

Then wait 30 seconds.

Then, disconnect the power cable, at the battery end.

It might be useful to do a quick camera hardware check.

On the laptop, create two Byobu windows.

You will use the two windows as follows:

• In the first window, you will launch the nodes that control the camera.
• In the second window, you will launch programs to monitor the data flow.

In the first window, we will launch the nodes that control the camera.

Activate ROS:

duckiebot $ source environment.sh

Run the launch file called camera.launch:

duckiebot $ roslaunch duckietown camera.launch veh:=![robot name]

At this point, you should see the red LED on the camera light up continuously.

In the terminal you should not see any red message, but only happy messages like the following:

![...]
[INFO] [1502539383.948237]: [/![robot name]/camera_node] Initialized.
[INFO] [1502539383.951123]: [/![robot name]/camera_node] Start capturing.
[INFO] [1502539384.040615]: [/![robot name]/camera_node] Published the first image.

Switch to the second window.

Activate the ROS environment:

duckiebot $ source environment.sh

ROS nodes can be launched in two ways:

1. “local launch”: log in to the Raspberry Pi using SSH and run the program from there.
2. “remote launch”: run the program directly from a laptop.

Which is better when is a long discussion that will be done later. Here we set up the “remote launch”.

As you did on the Duckiebot, you should clone the Software repository in the ~/duckietown directory.

Then, you should build the repository.

You have to edit the machines files on your laptop, as you did on the Duckiebot.

Now you are ready to launch the joystick demo remotely.

laptop $ ssh ![username]@![robot name].local

Run this on the laptop:

laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=![robot name]

You should be able to drive the vehicle with joystick just like the last example. Note that remotely launching nodes from your laptop doesn’t mean that the nodes are running on your laptop. They are still running on the Raspberry Pi in this case.

Also, you might have notice that the terminal where you launch the launch file is not printing all the printouts like the previous example. This is one of the limitation of remote launch.

Don’t worry though, we can still see the printouts using rqt_console.

On the laptop, open a new terminal window, and run:

laptop $ export ROS_MASTER_URI=http://![robot name].local:11311/
laptop $ rqt_console

AC: I could not see any messages in rqt_console - not sure what is wrong.

You should see a nice interface listing all the printouts in real time, completed with filters that can help you find that message you are looking for in a sea of messages.

You can use Ctrl-C at the terminal where roslaunch was executed to stop all the nodes launched by the launch file.

remote[![robot name].local-0]: failed to launch on ![robot name]:

Unable to establish ssh connection to [![username]@![robot name].local:22]:
Server u'![robot name].local' not found in known_hosts.

We are assuming that the joystick demo in Chapter 19 worked.

We are assuming that the procedure in Chapter 18 succeeded.

We also assume that you terminated all instances of roslaunch with Ctrl-C, so that currently there is nothing running in any window.

On the laptop, this time create four Byobu windows.

You will use the four windows as follows:

• In the first window, you will run the joystick demo, as before.
• In the second window, you will launch the nodes that control the camera.
• In the third window, you will launch programs to monitor the data flow.
• In the fourth window, you will use rviz to see the camera image.

In the first window, launch the joystick remotely using the same procedure in Section 19.4.

laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=![robot name]

You should be able to drive the robot with the joystick at this point.

In the second window, we will launch the nodes that control the camera.

The launch file is called camera.launch:

laptop $ source environment.sh
laptop $ roslaunch duckietown camera.launch veh:=![robot name]

You should see the red led on the camera light up.

Open a third terminal on the laptop.

You can see a list of topics currently on the ROS_MASTER with the commands:

laptop $ source environment.sh
laptop $ export ROS_MASTER_URI=http://![robot name].local:11311/
laptop $ rostopic list

You should see the following:

/diagnostics
/![robot name]/camera_node/camera_info
/![robot name]/camera_node/image/compressed
/![robot name]/camera_node/image/raw
/![robot name]/joy
/![robot name]/wheels_driver_node/wheels_cmd
/rosout
/rosout_agg

Launch rviz by using these commands:

laptop $ source environment.sh
laptop $ source set_ros_master.sh ![robot name]
laptop $ rviz

In the rviz interface, click “Add” on the lower left, then the “By topic” tag, then select the “Image” topic by the name

/![robot name]/camera_node/image/compressed

Then click “ok”. You should be able to see a live stream of the image from the camera.

To stop the nodes: You can stop the node by pressing Ctrl-C on the terminal where roslaunch was executed. In this case, you can use Ctrl-C in the terminal where you launched the camera.launch.

You should see the red light on the camera turn off in a few seconds.

Note that the joystick.launch is still up and running, so you can still drive the vehicle with the joystick.

Instead of using:

$ export ROS_MASTER_URI=http://![robot name].local:11311/

You can use the “set_ros_master.sh” script in the repo:

$ source set_ros_master.sh ![robot name]

Note that you need to use source; without that, it will not work.

Instead of using

$ ssh ![username]@![robot name].local

You can set up SSH so that you can use:

$ ssh my-robot

To do this, create a host section in ~/.ssh/config with the following contents:

Host my-robot
    User ![username]
    Hostname ![robot name].local

Here, you can choose any other string in place of “my-robot”.

Note that you cannot do

$ ping my-robot

You haven’t created another hostname, just an alias for SSH.

However, you can use the alias with all the tools that rely on SSH, including rsync and scp.

The LaTeX symbols definitions are in a file called docs/symbols.tex.

Put all definitions there; if they are centralized it is easier to check that they are coherent.

If $x$ is a function of time, use $x_t$ rather than $x(t)$.

Here are some useful symbols.

States and poses:

Our example account is the following:

Github name: greta-p
E-mail: greta-p@duckietown.com

Create a Github account (Figure 23).

Go to your inbox and verify the email.

Give the administrators your account name. They will invite you.

Accept the invitation to join the organization that you will find in your email.

You will do this procedure twice: once for the public key created on the laptop, and later with the public key created on the robot.

Go to settings (Figure 24).

Add the public key that you created:

To check that all of this works, use the command

$ ssh -T git@github.com

The command tries to connect to Github using the private keys that you specified. This is the expected output:

Warning: Permanently added the RSA host key for IP address '![ip address]' to the list of known hosts.
Hi ![username]! You've successfully authenticated, but GitHub does not provide shell access.

If you don’t see the greeting, stop.

Repeat what you just did for the Duckiebot on the laptop as well, making sure to change the name of the file containing the private key.

• UNIX
• Linux
• free software; open source software.

• Encryption
• Public key authentication

This installs the client:

$ sudo apt install ssh

This installs the server:

This enables the server:

The SSH configuration as a client is in the file

~/.ssh/config

Create the directory with the right permissions:

$ mkdir ~/.ssh
$ chmod 0700 ~/.ssh

Then add the following lines:

HostKeyAlgorithms ssh-rsa

The reason is that Paramiko, used by roslaunch, does not support the ECSDA keys.

To log in to a remote computer ![remote] with user ![remote-user], use:

$ ssh ![remote-user]@![remote]

This is a step that you will repeat twice: once on the Duckiebot, and once on your laptop.

The program will prompt you for the filename on which to save the file.

Use the convention

/home/![username]/.ssh/![username]@![host name]
/home/![username]/.ssh/![username]@![host name].pub

where:

• ![username] is the current user name that you are using (ubuntu or your chosen one);
• ![host name] is the name of the host (the Duckiebot or laptop);

An SSH key can be generated with the command:

$ ssh-keygen -h

The session output will look something like this:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/![username]/.ssh/id_rsa):

At this point, tell it to choose this file:

/home/![username]/.ssh/![username]@![host name]

Then:

Enter passphrase (empty for no passphrase):

Press enter; you want an empty passphrase.

Enter same passphrase again:

Press enter.

Your identification has been saved in /home/![username]/.ssh/![username]@![host name]
Your public key has been saved in /home/![username]/.ssh/![username]@![host name].pub
The key fingerprint is:
![XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX] ![username]@![host name]
The key's randomart image is:
+--[ RSA 2048]----+
|            .    |
|       o   o  .  |
|      o = o  . o |
|       B . .  * o|
|        S o    O |
|         o o  . E|
|          o o  o |
|           o  +  |
|            .. . |
+-----------------+

Note that the program created two files.

The file that contains the private key is

/home/![username]/.ssh/![username]@![host name]

The file that contains the public key has extension .pub:

/home/![username]/.ssh/![username]@![host name].pub

Next, tell SSH that you want to use this key.

Make sure that the file ~/.ssh/config exists:

$ touch ~/.ssh/config

Add a line containing

IdentityFile ![PRIVATE_KEY_FILE]

(using the filename for the private key).

Check that the config file is correct:

$ cat ~/.ssh/config
![...]
IdentityFile ![PRIVATE_KEY_FILE]
![...]

First, connect the two computers to the same network, and make sure that you can ping ![remote] from ![local]:

![local] $ ping ![remote].local

Do not continue if you cannot do this successfully.

If you have created a keypair for ![local-user], you will have a public key in this file on the ![local] computer:

/home/![local-user]/.ssh/![local-user]@![local].pub

This file is in the form:

ssh-rsa ![long list of letters and numbers] ![local-user]@![local]

You will have to copy the contents of this file on the ![remote] computer, to tell it that this key is authorized.

On the ![remote] computer, edit or create the file:

/home/![remote-user]/.ssh/authorized_keys

and add the entire line as above containing the public key.

Now, from the ![local] computer, try to log in into the ![remote] one:

![local] $ ssh ![remote-user]@![remote]

This should succeed, and you should not be asked for a password.

Sometimes, SSH does not work because you have the wrong permissions on some files.

In doubt, these lines fix the permissions for your .ssh directory.

$ chmod 0700 ~/.ssh
$ chmod 0700 ~/.ssh/*

To do quick changes to files, especially when logged remotely, we suggest you use the VI editor, or more precisely, VIM (“VI iMproved”).

• Git
• GitFlow

The basic Git program is installed using

$ sudo apt install git

Additional utilities for git are installed using:

$ sudo apt install git-extras

This include the git-ignore utility.

This should be done twice, once on the laptop, and later, on the robot.

These options tell Git who you are:

$ git config --global user.email "![email]"
$ git config --global user.name  "![full name]"

Also do this, and it doesn’t matter if you don’t know what it is:

$ git config --global push.default simple

You need to learn to use Byobu. It will save you much time later.

• Python
• Python tutorial

Install using:

$ sudo apt install virtualenv

matplotlib
seaborne
numpy
panda
scipy
opencv
...

This part installs ROS. You will run this twice, once on the laptop, once on the robot.

The first commands are copied from this page.

Tell Ubuntu where to find ROS:

$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

Tell Ubuntu that you trust the ROS people (they are nice folks):

$ sudo apt-key adv --keyserver hkp://ha.pool.sks-keyservers.net:80 --recv-key 421C365BD9FF1F717815A3895523BAEEB01FA116

Fetch the ROS repo:

$ sudo apt update

Now install the mega-package ros-kinetic-desktop-full.

$ sudo apt install ros-kinetic-desktop-full

There’s more to install:

$ sudo apt install ros-kinetic-{tf-conversions,cv-bridge,image-transport,camera-info-manager,theora-image-transport,joy,image-proc,compressed-image-transport,phidgets-drivers,imu-complementary-filter,imu-filter-madgwick}

: not done in aug20 image:

Initialize ROS:

$ sudo rosdep init
$ rosdep update

The idea is to add to what-the-duck all the tests that can be automated.

The documentation about to do that is not ready yet.

The current tests are available in the file:

./catkin_ws/src/f23-LED/led_detection/include/what_the_duck/list_of_checks.py

Here’s the list of tests already added:

✓  Camera is detected
✓  Scipy is installed
✓  sklearn is installed
✓  Date is set correctly
✓  Not running as root
✓  Not running as ubuntu
✓  Member of group sudo
✓  Member of group input
✓  Member of group video
✓  Member of group i2c
✓  ~/.ssh exists
✓  ~/.ssh permissions
✓  ~/.ssh/config exists
✓  SSH option HostKeyAlgorithms is set
✓  At least one key is configured.
✓  ~/.ssh/authorized_keys exists
✓  Git configured
✓  Git email set
✓  Git name set
✓  Git push policy set
✓  Edimax detected
✓  The hostname is configured
✓  /etc/hosts is sane
✓  Correct kernel version
✓  Messages are compiled
✓  Shell is bash
✓  Working internet connection
✓  Github configured
✓  Joystick detected
✓  Environment variable DUCKIETOWN_ROOT
✓  ${DUCKIETOWN_ROOT} exists
✓  Wifi network configured

Please add below any configuration test that can be automated:

• Check that all the rosX command resolve to a file/opt/ros/kinetic/bin/rosX.

• Make sure that packages such as python-roslaunch are not installed. (The user is invited to install it when roslaunch is not found!)

• Repository remote is not https.

• Editor is set to vim.

• They put the right MAC address in the network configuration

☐ The name of the package is package_![handle]

☐ The directory is in …

☐ The messages are called ….

☐ there is a readme file

☐ there is the first launch file

The first rule of Duckietown

The first rule of Duckietown is: you don’t talk about Duckietown, using email.

Instead, we use a communication platform called Slack.

There is one exception: inquiries about “meta” level issues, such as course enrollment and other official bureaucratic issues can be communicated via email.

The second rule of Duckietown

The second rule of Duckietown is: be kind and respectful, and have fun.

The third rule of Duckietown

The third rule of Duckietown is: read the instructions carefully.

Do not blindly copy and paste.

Only run a command if you know what it does.

At ETHZ, UdeM, TTIC, the class will be more-or-less synchronized. The materials are the same; there is some slight variation in the ordering.

Moreover, there will be some common groups for the projects.

The NCTU class is undergraduate level. Students will learn slightly simplified materials. They will not collaborate directly with the classes.

To participate in Duckietown, students must use two accounts: Slack and Github.

As an instructor/TA for the Fall 2017 class, in addition to the accounts above, these are two more accounts that you need.

• Have a Github account. See Chapter 74. See name conventions (TODO).
• Be part of the Duckietown Github organization. You are sure only when you commit and push one change to one of our repositories.
• Be part of the Duckietown Slack. See name conventions (TODO).

• Be signed up on

On each Duckiebot it is possible to log in as the ubuntu user using a common key.

Now, let’s set up passwordless SSH, so that you don’t need to type a password.

On the laptop, create the .ssh directory:

laptop $ mkdir -p ~/.ssh

The key duckietown_key1 is found at the URL:

https://www.dropbox.com/s/q23qptu01u7ur3y/duckietown_key1?dl=1

Download the file and call it ~/.ssh/duckietown_key1

laptop $ curl -o ~/.ssh/duckietown_key1 ![URL above]

Edit the permission of the file. SSH wants the key file to be not readable or writable from other users or groups.

laptop $ chmod 600 ~/.ssh/duckietown_key1

Regenerate the public key according to:

laptop $ ssh-keygen -f ~/.ssh/duckietown_key1 -y > ~/.ssh/duckietown_key1.pub

On the laptop, now edit ~/.ssh/config and add the following lines:

Host ![robot name]
  Hostname ![robot name].local
  User ![user name]
  IdentityFile ~/.ssh/duckietown_key1
  HostKeyAlgorithms ssh-rsa

Now you should be able to connect without using a password.

The following command should connect without a password being asked:

laptop $ ssh ubuntu@![robot name]